home *** CD-ROM | disk | FTP | other *** search
/ IRIX Base Documentation 2002 November / SGI IRIX Base Documentation 2002 November.iso / usr / share / catman / p_man / cat3 / librw / RWFileManager.z / RWFileManager
Encoding:
Text File  |  2002-10-03  |  6.3 KB  |  133 lines
  1.  
  2.  
  3.  
  4. RRRRWWWWFFFFiiiilllleeeeMMMMaaaannnnaaaaggggeeeerrrr((((3333CCCC++++++++))))                                        RRRRWWWWFFFFiiiilllleeeeMMMMaaaannnnaaaaggggeeeerrrr((((3333CCCC++++++++))))
  5.  
  6.  
  7.  
  8. NNNNaaaammmmeeee
  9.      RWFileManager - Rogue Wave library class
  10.  
  11. SSSSyyyynnnnooooppppssssiiiissss
  12.               typedef long     RWoffset ;
  13.  
  14.  
  15.  
  16.               typedef unsigned long   RWspace;  // (typically)
  17.           #include <rw/filemgr.h>
  18.           RWFileManager f("file.dat");
  19.  
  20.  
  21.  
  22.  
  23. DDDDeeeessssccccrrrriiiippppttttiiiioooonnnn
  24.      Class RRRRWWWWFFFFiiiilllleeeeMMMMaaaannnnaaaaggggeeeerrrr allocates and deallocates storage in a disk file,
  25.      much like a "freestore" manager.  It does this by maintaining a linked
  26.      list of free space within the file.  NNNNooootttteeee:  Class RRRRWWWWFFFFiiiilllleeeeMMMMaaaannnnaaaaggggeeeerrrr inherits
  27.      class RRRRWWWWFFFFiiiilllleeee as a public base class; hence all the public member
  28.      functions of RRRRWWWWFFFFiiiilllleeee are visible to RRRRWWWWFFFFiiiilllleeeeMMMMaaaannnnaaaaggggeeeerrrr.  They are not listed
  29.      here.  If a file is managed by an RRRRWWWWFFFFiiiilllleeeeMMMMaaaannnnaaaaggggeeeerrrr then reading or writing
  30.      to unallocated space in the file will have undefined results.  In
  31.      particular, overwriting the end of allocated space is a common problem
  32.      which usually results in corrupted data.  One way to encounter this
  33.      problem is to use bbbbiiiinnnnaaaarrrryyyySSSSttttoooorrrreeeeSSSSiiiizzzzeeee(((()))) to discover the amount of space
  34.      needed to store an RRRRWWWWCCCCoooolllllllleeeeccccttttiiiioooonnnn.  For most purposes, the storage size of
  35.      an RRRRWWWWCCCCoooolllllllleeeeccccttttiiiioooonnnn is found using the RRRRWWWWCCCCoooolllllllleeeeccccttttaaaabbbblllleeee method
  36.      rrrreeeeccccuuuurrrrssssiiiivvvveeeeSSSSttttoooorrrreeeeSSSSiiiizzzzeeee(((()))).
  37.  
  38. PPPPeeeerrrrssssiiiisssstttteeeennnncccceeee
  39.      None
  40.  
  41. PPPPuuuubbbblllliiiicccc CCCCoooonnnnssssttttrrrruuuuccccttttoooorrrr
  42.               RRRRWWWWFFFFiiiilllleeeeMMMMaaaannnnaaaaggggeeeerrrr(const char* filename, const char* mode = 0);
  43.  
  44.  
  45.      Constructs an RRRRWWWWFFFFiiiilllleeeeMMMMaaaannnnaaaaggggeeeerrrr for the file with path name ffffiiiilllleeeennnnaaaammmmeeee using
  46.      mode mmmmooooddddeeee.  The mode is as given by the Standard C library function
  47.      ffffooooppppeeeennnn(((()))).  If mmmmooooddddeeee is zero (the default) then the constructor will attempt
  48.      to open an existing file with the given filename for update (mode "rrrrbbbb++++").
  49.      If this is not possible, then it will attempt to create a new file with
  50.      the given filename (mode "wwwwbbbb++++").  If the file exists and is not empty,
  51.      then the constructor assumes it contains an existing file manager; other
  52.      contents will cause an exception of type RRRRWWWWEEEExxxxtttteeeerrrrnnnnaaaallllEEEErrrrrrrr to be thrown.  If
  53.      no file exists or if an existing file is empty, then the constructor will
  54.      attempt to create the file (if necessary) and initialize it with a new
  55.      file manager. The resultant object should be checked for validity using
  56.  
  57.  
  58.  
  59.  
  60.  
  61.  
  62.  
  63.                                                                         PPPPaaaaggggeeee 1111
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. RRRRWWWWFFFFiiiilllleeeeMMMMaaaannnnaaaaggggeeeerrrr((((3333CCCC++++++++))))                                        RRRRWWWWFFFFiiiilllleeeeMMMMaaaannnnaaaaggggeeeerrrr((((3333CCCC++++++++))))
  71.  
  72.  
  73.  
  74.      function iiiissssVVVVaaaalllliiiidddd(((()))).  A possible exception that could occur is RRRRWWWWFFFFiiiilllleeeeEEEErrrrrrrr.
  75.  
  76. PPPPuuuubbbblllliiiicccc MMMMeeeemmmmbbbbeeeerrrr FFFFuuuunnnnccccttttiiiioooonnnnssss
  77.               RWoffset
  78.           aaaallllllllooooccccaaaatttteeee(RWspace s);
  79.  
  80.  
  81.      Allocates ssss bytes of storage in the file.  Returns the offset to the
  82.      start of the storage location.  The very first allocation for the file is
  83.      considered "special" and can be returned at any later time by the
  84.      function ssssttttaaaarrrrtttt(((()))).  A possible exception that could occur is RRRRWWWWFFFFiiiilllleeeeEEEErrrrrrrr.
  85.  
  86.               void
  87.           ddddeeeeaaaallllllllooooccccaaaatttteeee(RWoffset t);
  88.  
  89.  
  90.      Deallocates (frees) the storage space starting at offset tttt.  This space
  91.      must have been previously allocated by a call to aaaallllllllooooccccaaaatttteeee(((()))).  The very
  92.      first allocation ever made in the file is considered "special" and cannot
  93.      be deallocated.  A possible exception that could occur is RRRRWWWWFFFFiiiilllleeeeEEEErrrrrrrr.
  94.  
  95.               RWoffset
  96.           eeeennnnddddDDDDaaaattttaaaa();
  97.  
  98.  
  99.      Returns an offset just past the end of the file.
  100.  
  101.               RWoffset
  102.           ssssttttaaaarrrrtttt();
  103.  
  104.  
  105.      Returns the offset of the first space ever allocated for data in this
  106.      file.  If no space has ever been allocated, returns RRRRWWWWNNNNIIIILLLL.  This is
  107.      typically used to "get started" and find the rest of the data in the
  108.      file.
  109.  
  110.  
  111.  
  112.  
  113.  
  114.  
  115.  
  116.  
  117.  
  118.  
  119.  
  120.  
  121.  
  122.  
  123.  
  124.  
  125.  
  126.  
  127.  
  128.  
  129.                                                                         PPPPaaaaggggeeee 2222
  130.  
  131.  
  132.  
  133.